Loadstar 128 #10/q10.d81/t.shell asm

Text File | 1990-01-01 | 19.1 KB | 496 lines

           L O A D S T A R   1 2 8   E D I T O R / A S S E M B L E R

                             by Robert Rockefeller


    The Loadstar 128 Editor/Assembler package is a necessary tool for
writing machine language.  You must know how to do it already -- this will
not teach you -- but it will make it a LOT easier.  This article will only
document the assembler/editor features.

    The editor, named "COM.EDT", and the assembler, named "COM.ASM", are
designed to be used in conjunction with the shell program published on this
issue of LOADSTAR.  Execute the shell program by typing RUN"128 SHELL" then
type RETURN.

EDITOR
------

    The editor is a full-screen programmer's text editor which creates PET
ASCII program files.  A programmer's text editor differs from a
wordprocessor in that it typically cannot format and print out text files.
It's for editing code only.

    After the shell is loaded, you execute the editor by typing EDT then
RETURN.  A file can be specified for editing by following EDT with a
filename.  For example, if EDT "ASM.COPY is executed the editor will be
loaded, then the text file "ASM.COPY" will automatically be loaded into the
editor from disk device 8.  An alternate device number for the text file can
be specified by prefixing it to the filename.  For example, EDT 9,"ASM.COPY
would try to load "ASM.COPY" from device 9.

    EDT can work on files completely in RAM by specifying EDT RAM instead of
a filename.  Typically you would use EDT to create a text file to be
assembled.  You would then exit the editor and assemble the file with ASM.
You could then type EDT RAM to re-edit the text already in RAM without the
necessity of loading the text in from disk.  Of course you must be sure that
the text has not been corrupted in any way in the meantime.  Therefore avoid
loading in BASIC programs between uses of EDT if you wish to use the RAM
option.  It is also a good idea to save a copy of your source code to disk
after making changes just in case.

    EDT files are suitable for use by the "COM.SUBMIT" program published
with the shell program. SUBMIT allows you to execute text in "SUB." files as
if the text were entered at the keyboard.  You can use "SUB." files to
redefine the function keys, RUN BASIC programs, control the assembler, etc.
If you're familiar with MS DOS, think of "SUB." files as "batch" files.

    Some keyboard conventions are used when explaining EDT functions.  F1 @
means type the F1 key and release it, then type the @ key and release it.  A
slash (/) is used to show that two keys are to be pressed simultaneously.
SHIFT/RETURN means press a SHIFT key and the RETURN key at the same time.
EDT functions are explained below.

ESC 1 - Set the text color.

ESC 2 - Set the screen color.

ESC @ - Clear text from the cursor position to the end of the file.

ESC a - Turn insert mode on.

ESC c - Turn insert mode off.

ESC d - Erase the whole line.

ESC g - Enable bell ringing for errors.

ESC h - Disable bell ringing for errors.

ESC j - Move the cursor to the start of the line.

ESC k - Move the cursor to the end of the line.

ESC n - Set the screen to normal (non-reversed) mode.

ESC p - Erase to the start of the line.

ESC q - Erase to the end of the line.

ESC r - Set the screen to reversed mode.

ESC v - Scroll the screen up.

ESC w - Scroll the screen down.

F1 @ - Read the disk error channel, or issue a disk command.  Type F1 @
RETURN to read the error channel of the default disk drive.  To read some
other device enter a device number followed by a comma.  For example type F1
@ 9, RETURN to read the error channel of device 9.  To issue a disk command
just type F1 @ then type the command at the prompt, and type RETURN.  To
send a command to a device other than the default device number, just prefix
the device number to the command.  For example, typing F1 @ 9,i0 RETURN
would initialize disk device 9.

F1 d - Set the default disk device number.  The default disk device number
is always displayed as the number at the extreme left of the status line.

F1 m - Display the number of free bytes available for text storage.

F1 s - Search for a string.  Just enter the string at the prompt and type
RETURN.

F1 e - Save the editor to disk.  First select the screen colors you like
with ESC 1 and ESC 2, then type F1 e, then enter the disk device number to
which you wish to save the editor, then type RETURN.

F1 r - Replace a string.  First enter the string to be replaced, then enter
the string to replace with.  Finally, if you wish to be prompted before each
replacement type y at the PROMPT BEFORE REPLACING? prompt, else type n.

F1 v - Display a text file on disk.  Enter the name of the file you wish to
view then type RETURN.  The file will be printed to the screen.  To view
from a disk other than the default disk you prefix a device number to the
filename. For example, if you enter a filename of 9,ERR.COPY the file
"ERR.COPY" would be displayed from device 9.

F1 b - Exit the editor.  Return to the BASIC environment.

RETURN - Start a new line.  Inserts a carriage-return character into the
text area.  Any text to the right of the cursor will be moved to the next
line when RETURN is typed.

CONTROL/p - Insert the text buffer at the cursor position.  Text can be
copied into the text buffer by marking a block (see SHIFT/F7) then typing c.

SHIFT/HOME - Clear all text.  You must type y at the prompt before text is
actually cleared.

HELP - Display help screens.

DEL - Delete the character to the left of the cursor.

CRSR keys - Work as you would expect them to.

down-arrow - Scroll the screen down one row.

up-arrow - Scroll the screen up one row.

HOME up-arrow - Move the cursor to the top, left corner of the screen.

HOME down-arrow - Move the cursor to the bottom, left corner of the screen.

HOME left-arrow - Move the cursor to the start of the text area.

HOME right-arrow - Move the cursor to the end of the text.

HOME cursor-down - Goto a specified line number.  Type the number of the
line you wish to go to, then type RETURN.

F3 - Display a disk directory.  Enter the device number of the disk you wish
to view.

F5 - Save the text to a disk drive.  Enter the filename at the prompt.  To
save to a disk other than the default disk you prefix a device number to the
filename.  For example, if you enter a filename of 9,SUB.KEYS the text would
be saved to disk device 9 with the name "SUB.KEYS".

F7 - Delete the character under the cursor.

F2 - Load a file.  Enter the name of the file you wish to load.  To load
from a disk other than the default you prefix a device number to the
filename.  For example, if you enter a filename of 9,SUB.KEYS the file
"SUB.KEYS" would be loaded from device 9.

F4 - Search ahead for the next occurrence of the last string searched for.

F8 - Begin marking a text block.  Move the cursor to the other end of the
block.  The block is displayed in reverse field as the cursor is moved.
After the block is marked there are three operations that can be performed
on the block.

    Type s to save the block to disk.

    Type c to copy the block to the text buffer.  The block can be inserted
into the text area with CONTROL/p.

    Type DEL to delete the block.  The block is copied to the text buffer
before deletion.  The block can be recovered with CONTROL/p.

ASSEMBLER
---------

    The assembler is executed by typing ASM and the name of a file to
assemble, then RETURN.  For example, if ASM "COPY is executed the assembler
will be loaded, then the source file "ASM.COPY" will be assembled.  All
assembler source files must have ASM.  as the first four characters of their
filenames.  However, leave off the ASM.  prefix when specifying filenames
for the assembler.  The assembler automatically adds ASM. to each filename.

    ASM can assemble files completely in RAM by specifying ASM RAM instead
of a filename.  Typically you would use EDT to create a text file to be
assembled.  You would then exit the editor, and type ASM RAM to assemble the
text already in memory without the necessity of loading the text in from
disk.  If you load in a BASIC program in the meantime, however, the
assembler may have been corrupted.

    In addition to a source filename a number of commands can be passed to
the assembler.  They are:

a - Specify primary source device number.  This device is checked first for
source files.  The default device number is 8.  For example, if ASM "COPY"
A9 is specified device 9 will be searched first for source files.

b - Specify secondary source device number.  The default device number is 9.
 This device is checked second for source files, only if a source file is
not found on the primary device.  For example, if ASM "COPY" B8 is specified
device 8 will be searched second for source files.

e - Specify which device to send the error file to.  A device number of 0
disables error output.  The default device is 3, the screen.  However an
error file can be sent to a printer or disk also.  Error files output to
disk will have the letters ERR.  prefixed to the filename.  For example, if
ASM "COPY" E9 is specified an error file with filename "ERR.COPY" would be
sent to device 9.

p - Specify which device to send the printout file to.  A device number of 0
disables list output.  The default device number is 0.  A listing file can
be sent to the screen, a printer, or to a disk.  Listing files output to
disk will have the letters PRN.  prefixed to the filename.  For example, if
ASM "COPY" P8 is specified a list file with filename "PRN.COPY" would be
sent to device 8.

s - Specify which device to save the symbol table on.  After assembly the
assembler can save the symbol table to disk.  A future symbolic debugger
will be able to load this symbol table to provide symbolic disassemblies.
Symbol tables saved to disk will have the letters SYM.  prefixed to the
filename.  For example, if ASM "COPY" S8 is specified the symbol table will
be saved with the filename "SYM.COPY" on device 8.

o - Specify which device to write the assembled program object code to.  The
default device is 8.  Assembled programs written to disk will have the
letters OBJ.  prefixed to the filename.  For example, if ASM "COPY" O9 is
specified the object code will be saved with the filename "OBJ.COPY" on
device 9.

l - Set maximum line length for the printout file.  The default length is 80
columns.  You might want to change this if outputting a listing to a
printer.  Line length can be set from 40 to 131 columns wide.

    There are several switches which can be used to select between several
assembler modes.  They are listed below:

-s  If a listing file is being produced by the assembler normally the source
code listing is produced followed by the printout of the symbol table.  The
-s switch disables output of the symbol table printout.

-l  If a listing file is being produced by the assembler normally the source
code listing is produced followed by the printout of the symbol table.  The
-l switch disables output of the source code listing.

+c  Normally the assembler ignores the case of symbols, that is, no
distinction is made between capital and lower case letters.  For example,
the assembler regards the symbols Label, label, and LABEL as identical.  The
+c switch enables case distinction so that capital and lower case letters
are regarded as different.

+f  The +f switch if enabled causes a line feed character to be printed
after a carriage-return during printout.  Some printers require this.

Example: ASM "PAINT" P4 A9 B8 O9 -L +F

Assemble the file "ASM.PAINT" with primary source device as 9, secondary 8.
Send a printout only of the symbol table to printer device 4, with line
feeds enabled.  Write the assembled object code to device 9 as "OBJ.PAINT".
Note the ASM command can be defined in a function key, or executed with a
SUBMIT file.

    Each assembly source line consists of four fields, the label field, the
opcode field, the operand field, and the comment field.  Each field must be
separated by one or more TAB characters and/or spaces.  On any given line
any or all of these fields may be missing.  Labels must be terminated with a
colon.  Comments must be preceded with a semi-colon.  This valid line
contains all four fields.

Label1: lda (txtptr),y   ;get a byte.

    The assembler accepts literals in three radices, decimal, hexadecimal,
and binary.  Character literals must be preceded by the single quote
character.  Note that character literals can be added, multiplied, etc.,
like any other number.  Examples are:

Decimal   234
Hex       $ff11
Binary    %10101111
Character 'a

    Assembler symbols may consist of the capital letters A to Z, lower case
letters a to z, the digits 0 to 9, or the underscore character (CMDR/@).
Symbols can be up to 31 characters long, but only the first 15 characters
are signifigant.  Labels must be terminated by a colon character :.  Equates
may be created with the = operator and must not be terminated by a colon.
Here is an example of an equate.

Chrout   = $ffd2

Here is an example of a valid label.

longlabel:

    The assembler has a fairly good expression evaluator with 11 operators,
and nested parenthesization.  An expression is any legal combination of
symbols, literals, and operators which the assembler will resolve to a
single number.  Operators have different precedence values.  Operators with
higher precedence are evaluated first.  Operators of the same precedence are
evaluated left to right.  For example consider the expression 2+3*3.  Is the
answer 15 or 11?  Since multiplication has a higher precedence the
multiplication is performed first and the answer is 11.  If it is necessary
for the addition to be performed first group it in parentheses like this
(2+3)*3.  The operators and their precedence values are listed below.

Operator  Explanation      Precedence

unary - two's complement     7
<       low byte             7
>       high byte            7
*       multiply             6
/       divide               6
//      modulus              6
+       addition             5
-       subtraction          5
&       logical and          4
!       logical exclusive-or 3
{$7d}       logical or           2

    You must be careful when using parentheses to group sub-expressions
since the assembler uses enclosing parentheses to indicate indirect
addressing mode.  For example:

   lda (30+2)*(5+6),y

Although absolute addressing mode is desired here the assembler will try to
assemble this instruction with indirect indexed mode due to the enclosing
parentheses.  To avoid this problem prefix a plus sign when absolute
addressing mode is needed, like this:

   lda +(30+2)*(5+6),y

The plus sign doesn't affect the value of the expression, and prevents the
assembler from using the incorrect mode.

    The asterisk * is used as special symbol by the assembler and always
equals the current value of the Program Counter.  As such the asterisk can
be used in expressions like any other number.  For example, the following
two instructions are equivalent.  Both jump to themselves.

Label1: jmp Label1

       jmp *

    The assembler has 15 directives which are explained below.

 .list
 .nolist

Enable or disable listing output to the printout device.  Note that the
symbol table printout is not affected by these two commands.

 .nosym

Disable output of the symbol table printout to the printout device.

 .nohdr

Disable the printing of headers at the top of each page during printout.

 .gen
 .nogen

Sometimes the .byte, .word, or .dbyte commands generate more than three
bytes per line.  .gen enables the listing of all generated bytes.  .nogen
causes only the first 3 generated bytes to be listed.

 .page

This directive causes blank lines to be printed until the current printout
page is finished off, then a new page is started.

 .space

Specify that a number of blank lines be printed to the printout device.  For
example .space 5 would cause five blank lines to be output.

 .title

Define the program title which will be printed at the top of each printout
page if headers are enabled.  See .nohdr above.  Example: .title Super
Database

 .end

The .end directive terminates assembly.  Each assembler program must contain
the .end directive exactly once at the end of the program.

 .include

This directive is used to load further source files from disk.  Practically
speaking, the assembler will substitute the source file text for the
.include directive.  The assembler always loads source files into memory in
their entirety, so combined source file size must be such that a source file
containing an .include, and the included file must both be able to fit in
memory at once.  When specifying the name of the file to be loaded do not
use the ASM.  prefix.  The assembler adds this prefix automatically.  For
example, .include buffers would load the file "ASM.BUFFERS".

 .byte

This directive accepts a number of expressions which must evaluate to 8-bit
values.  Each value is then output to the object device.  Strings may be
included and must be enclosed in double quotes.  Use commas as separators.
Example:

 .byte 13,13,"this is a string",0

 .word

This directive accepts a number of expressions which must evaluate to 16-bit
values.  Each value is then output to the object device with the low byte
being output first.  Use commas as separators.  Example:

 .word $ff22,ArgTable,3

 .dbyte

This directive accepts a number of expressions which must evaluate to 16-bit
values.  Each value is then output to the object device with the high byte
being output first.  Use commas as separators.  Example:

 .dbyte $ff22,ArgTable,3

 .rmb
 *=*+

These directives are functionally equivalent and are used to allocate memory
for variables, buffers, etc.  The examples below would allocate two bytes.

 .rmb 2
 *=*+2

 *=

Assign a value to the assembler Program Counter.  This is normally done
prior to defining zero page variables, and prior to generating code.  For
example:

 *= 2
zpvar1: .rmb 2  ;create zero page variables.
zpvar2: .rmb 2
 *= $1c03       ;generate code.
 lda #5         ;the program starts here.

    The assembler has comprehensive error checking with two types of errors,
fatal and non-fatal.  Fatal errors immediately suspend assembly.  If a
non-fatal error occurs the assembler will continue assembly but will report
the error through the error file and the printout file.  The error numbers
and their meanings are listed below.

Fatal Error  Meaning

 0  RUN/STOP was pressed.
 1  disk error.
 3  error was returned by disk error channel.
 4  couldn't find a file.
 5  device not present.
 6  missing filename.
 7  source file was corrupted.
 8  out of memory.
 9  illegal device number.
 10 line too long.
 11 symbol table overflow.

Error  Meaning

 0  multiply defined symbol.
 1  illegal character in symbol.
 2  undefined symbol was referenced.
 3  branch out of range.
 4  mismatched parenthesis.
 5  invalid expression.
 6  expression was too complex.
 7  division by zero error.
 8  missing operand.
 9  syntax error.
 10 16-bit value where 8-bit value was required.
 11 incomplete addressing mode specification.
 14 symbol was too long.
 15 phase error.  Program Counter was out of phase on passes 1 and 2.
 16 wasted byte.  Assembler used absolute mode where zero page
    addressing mode would suffice.  Caused by a forward reference to
    a zero page variable.
 17 invalid addressing mode.
 19 overflowed 64K RAM bank.

RR
                             **** End of Text ****